# EntityPersister.java

    package org.codefilarete.stalactite.engine;

    import java.util.Collection;
    import java.util.Collections;
    import java.util.List;
    import java.util.Map;
    import java.util.Set;
    import java.util.function.Consumer;
    import java.util.function.Function;

    import org.codefilarete.reflection.AccessorByMethodReference;
    import org.codefilarete.reflection.AccessorChain;
    import org.codefilarete.reflection.Accessors;
    import org.codefilarete.reflection.ValueAccessPoint;
    import org.codefilarete.stalactite.engine.EntityCriteria.CriteriaPath;
    import org.codefilarete.stalactite.engine.EntityCriteria.FluentOrderByClause;
    import org.codefilarete.stalactite.engine.EntityCriteria.SerializableCollectionFunction;
    import org.codefilarete.stalactite.engine.listener.PersisterListener;
    import org.codefilarete.stalactite.mapping.SimpleIdMapping;
    import org.codefilarete.stalactite.mapping.id.manager.IdentifierInsertionManager;
    import org.codefilarete.stalactite.query.model.ConditionalOperator;
    import org.codefilarete.stalactite.query.model.JoinLink;
    import org.codefilarete.stalactite.query.model.Select;
    import org.codefilarete.stalactite.query.model.Selectable;
    import org.codefilarete.stalactite.sql.result.Accumulator;
    import org.codefilarete.tool.Duo;
    import org.codefilarete.tool.Experimental;
    import org.codefilarete.tool.collection.Arrays;
    import org.codefilarete.tool.collection.Iterables;
    import org.codefilarete.tool.collection.KeepOrderMap;
    import org.codefilarete.tool.collection.KeepOrderSet;
    import org.codefilarete.tool.collection.Maps;
    import org.codefilarete.tool.collection.PairIterator;
    import org.danekja.java.util.function.serializable.SerializableBiConsumer;
    import org.danekja.java.util.function.serializable.SerializableFunction;

    /**
     * @author Guillaume Mary
     */
    public interface EntityPersister<C, I> extends PersistExecutor<C>, InsertExecutor<C>, UpdateExecutor<C>, SelectExecutor<C, I>, DeleteExecutor<C, I>, PersisterListener<C, I> {

    	/**
    	 * Persists an instance either it is already persisted or not (insert or update).
    	 *
    	 * Check between insert or update is determined by id state which itself depends on identifier policy,
    	 * see {@link SimpleIdMapping#IsNewDeterminer} implementations and
    	 * {@link IdentifierInsertionManager} implementations for id value computation.
    	 *
    	 * @param entity an entity to be persisted
    	 * @throws StaleStateObjectException if updated row count differs from entities count
    	 * @see #insert(Iterable)
    	 * @see #update(Iterable, boolean)
    	 */
    	default void persist(C entity) {
    		// determine insert or update operation
    		persist(Collections.singleton(entity));
    	}

    	/**
    	 * Choose either to insert or update entities according to their persistent state.
    	 *
    	 * @param entities entities to be inserted or updated according to {@link #isNew(Object)} result
    	 */
    	void persist(Iterable<? extends C> entities);

    	default void insert(C entity) {
    		insert(Collections.singletonList(entity));
    	}

    	/**
    	 * Updates an instance that may have changes.
    	 * Groups statements to benefit from JDBC batch. Useful overall when allColumnsStatement
    	 * is set to false.
    	 *
    	 * @param modified the supposing entity that has differences against {@code unmodified} entity
    	 * @param unmodified the "original" (freshly loaded from database ?) entity
    	 * @param allColumnsStatement true if all columns must be in the SQL statement, false if only modified ones should be in
    	 */
    	default void update(C modified, C unmodified, boolean allColumnsStatement) {
    		update(Collections.singletonList(new Duo<>(modified, unmodified)), allColumnsStatement);
    	}

    	/**
    	 * Updates given entity in database according to following mechanism : it selects the existing data in database, then compares it with given
    	 * entity in memory, and then updates database if necessary (nothing if no change was made).
    	 *
    	 * @param entity the entity to be updated
    	 */
    	default void update(C entity) {
    		update(entity, true);
    	}

    	/**
    	 * Updates given entity in database according to following mechanism : it selects the existing data in database, then compares it with given
    	 * entity in memory, and then updates database if necessary (nothing if no change was made).
    	 *
    	 * @param entity the entity to be updated
    	 * @param allColumnsStatement true to include all columns in statement even if only a part of them are touched, false to target only modified ones
    	 */
    	default void update(C entity, boolean allColumnsStatement) {
    		update(entity, select(getId(entity)), allColumnsStatement);
    	}

    	/**
    	 * Updates given entities in database according to following mechanism : it selects the existing data in database, then compares it with given
    	 * entities in memory, and then updates database if necessary (nothing if no change was made).
    	 * To be used for CRUD use case.
    	 *
    	 * @param entities the entities to be updated
    	 */
    	default void update(Iterable<C> entities) {
    		// Below we keep order of given entities mainly to get steady unit tests. Meanwhile, this may have performance
    		// impacts but very difficult to measure
    		Set<I> ids = Iterables.collect(entities, this::getId, KeepOrderSet::new);
    		Set<C> entitiesFromDb = select(ids);
    		// Given entities may not be in same order than loaded ones from DB, whereas order is required for comparison (else everything is different !)
    		// so we join them by their id to make them match
    		Map<C, I> idPerEntity = Iterables.map(entities, Function.identity(), this::getId, KeepOrderMap::new);
    		Map<I, C> entityFromDbPerId = Iterables.map(entitiesFromDb, this::getId, Function.identity());
    		Map<C, C> modifiedVsUnmodifiedEntities = Maps.innerJoinOnValuesAndKeys(idPerEntity, entityFromDbPerId, KeepOrderMap::new);
    		update(() -> new PairIterator<>(modifiedVsUnmodifiedEntities.keySet(), modifiedVsUnmodifiedEntities.values()), true);
    	}

    	/**
    	 * Helping method for "Command Design Pattern" so one can apply modifications to the entity loaded by its id without any concern of loading it.
    	 * This implementation will load twice the entity, invoke given {@link Consumer} with one of them, and then call {@link #update(Object, Object, boolean)} afterward.
    	 * Subclasses may override this behavior to enhance loading or change its algorithm (by using {@link #updateById(Iterable)} for instance)
    	 *
    	 * @param id key of entity to be modified
    	 * @param entityConsumer business code expected to modify its given entity
    	 */
    	@Experimental
    	default void update(I id, Consumer<C> entityConsumer) {
    		update(Collections.singleton(id), entityConsumer);
    	}

    	/**
    	 * Massive version of {@link #update(Object, Consumer)}. {@link Consumer} will be called for each found entities.
    	 *
    	 * @param ids keys of entities to be modified
    	 * @param entityConsumer business code expected to modify its given entity
    	 */
    	@Experimental
    	default void update(Iterable<I> ids, Consumer<C> entityConsumer) {
    		Set<C> unmodified = select(ids);
    		Set<C> modified = select(ids);
    		modified.forEach(entityConsumer);
    		update(() -> new PairIterator<>(modified, unmodified), true);
    	}

    	/**
    	 * Deletes instances.
    	 * Takes optimistic lock into account.
    	 *
    	 * @param entity entity to be deleted
    	 * @throws StaleStateObjectException if deleted row count differs from the entities count
    	 */
    	default void delete(C entity) {
    		delete(Collections.singletonList(entity));
    	}

    	/**
    	 * Will delete instances only by their identifier.
    	 * This method will not take optimistic lock (versioned entity) into account, so it will delete database rows "roughly".
    	 *
    	 * @param entity entity to be deleted
    	 */
    	default void deleteById(C entity) {
    		deleteById(Collections.singletonList(entity));
    	}

    	default C select(I id) {
    		return Iterables.first(select(Collections.singleton(id)));
    	}

    	default Set<C> select(I... ids) {
    		return select(Arrays.asHashSet(ids));
    	}

    	/**
    	 * Creates a query with some criteria based on some properties.
    	 * Please note that the whole bean graph is loaded, not only entities that satisfy criteria.
    	 * Raises an exception if the targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param getter a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O> ExecutableEntityQuery<C, ?> selectWhere(SerializableFunction<C, O> getter, ConditionalOperator<O, ?> operator) {
    		return selectWhere(AccessorChain.fromMethodReference(getter), operator);
    	}

    	/**
    	 * Creates a query with some criteria based on some properties.
    	 * Please note that the whole bean graph is loaded, not only entities that satisfy criteria.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param setter a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O> ExecutableEntityQuery<C, ?> selectWhere(SerializableBiConsumer<C, O> setter, ConditionalOperator<O, ?> operator) {
    		return selectWhere(Arrays.asList(Accessors.mutatorByMethodReference(setter)), operator);
    	}

    	/**
    	 * Variation of {@link #selectWhere(SerializableFunction, ConditionalOperator)} with a criteria on property of a property
    	 * Please note that whole bean graph is loaded, not only entities that satisfy criteria.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param getter1 a property accessor
    	 * @param getter2 a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O, A> ExecutableEntityQuery<C, ?> selectWhere(SerializableFunction<C, A> getter1, SerializableFunction<A, O> getter2, ConditionalOperator<O, ?> operator) {
    		return selectWhere(AccessorChain.fromMethodReferences(getter1, getter2), operator);
    	}

    	/**
    	 * Creates a query with some criteria based on some properties.
    	 * Please note that the whole bean graph is loaded, not only entities that satisfy criteria.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param accessorChain a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O> ExecutableEntityQuery<C, ?> selectWhere(List<? extends ValueAccessPoint<?>> accessorChain, ConditionalOperator<O, ?> operator) {
    		return selectWhere().and(accessorChain, operator);
    	}

    	/**
    	 * Creates a query with some criteria based on some properties.
    	 * Please note that the whole bean graph is loaded, not only entities that satisfy criteria.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param accessorChain a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O> ExecutableEntityQuery<C, ?> selectWhere(AccessorChain<C, ?> accessorChain, ConditionalOperator<O, ?> operator) {
    		return selectWhere(accessorChain.getAccessors(), operator);
    	}

    	default <O> ExecutableEntityQuery<C, ?> selectWhere(CriteriaPath<C, ?> accessorChain, ConditionalOperator<O, ?> operator) {
    		return selectWhere(accessorChain.getAccessors(), operator);
    	}

    	default <O, S extends Collection<O>, NEXT> ExecutableEntityQuery<C, ?> selectWhere(SerializableCollectionFunction<C, S, O> accessor1, SerializableFunction<O, NEXT> accessor2, ConditionalOperator<NEXT, ?> operator) {
    		return selectWhere(new CriteriaPath<>(accessor1, accessor2), operator);
    	}

    	/**
    	 * Creates a query which criteria target mapped properties.
    	 * Please note that the whole bean graph is loaded, not only entities that satisfy criteria.
    	 *
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	ExecutableEntityQuery<C, ?> selectWhere();

    	/**
    	 * Creates a projection query which criteria target mapped properties.
    	 * {@link Select} must be modified by given select adapter (by default all column that would allow to load the entity are present).
    	 * User is expected to modify default {@link Select} by clearing it (optional) and add its {@link org.codefilarete.stalactite.query.model.Selectable}
    	 * ({@link org.codefilarete.stalactite.sql.ddl.structure.Column} or {@link org.codefilarete.stalactite.query.model.operator.SQLFunction}).
    	 * Consumption and aggregation of query result is left to the user that must implement its {@link Accumulator}
    	 * while executing the result of this method through {@link ExecutableProjection#execute(Accumulator)}.
    	 * <strong>Note that all {@link org.codefilarete.stalactite.query.model.Selectable} added to the Select must have an alias</strong>.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param selectAdapter the {@link Select} clause modifier
    	 * @param getter a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O> ExecutableProjectionQuery<C, ?> selectProjectionWhere(Consumer<SelectAdapter<C>> selectAdapter, SerializableFunction<C, O> getter, ConditionalOperator<O, ?> operator) {
    		return selectProjectionWhere(selectAdapter).and(getter, operator);
    	}

    	/**
    	 * Creates a projection query which criteria target mapped properties.
    	 * {@link Select} must be modified by given select adapter (by default all columns that would allow to load the entity are present).
    	 * User is expected to modify default {@link Select} by clearing it (optional) and add its {@link org.codefilarete.stalactite.query.model.Selectable}
    	 * ({@link org.codefilarete.stalactite.sql.ddl.structure.Column} or {@link org.codefilarete.stalactite.query.model.operator.SQLFunction}).
    	 * Consumption and aggregation of query result is left to the user that must implement its {@link Accumulator}
    	 * while executing the result of this method through {@link ExecutableProjection#execute(Accumulator)}.
    	 * <strong>Note that all {@link org.codefilarete.stalactite.query.model.Selectable} added to the Select must have an alias</strong>.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param selectAdapter the {@link Select} clause modifier
    	 * @param setter a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O> ExecutableProjectionQuery<C, ?> selectProjectionWhere(Consumer<SelectAdapter<C>> selectAdapter, SerializableBiConsumer<C, O> setter, ConditionalOperator<O, ?> operator) {
    		return selectProjectionWhere(selectAdapter).and(setter, operator);
    	}

    	/**
    	 * Creates a projection query which criteria target mapped properties.
    	 * {@link Select} must be modified by given select adapter (by default all columns that would allow to load the entity are present).
    	 * User is expected to modify default {@link Select} by clearing it (optional) and add its {@link org.codefilarete.stalactite.query.model.Selectable}
    	 * ({@link org.codefilarete.stalactite.sql.ddl.structure.Column} or {@link org.codefilarete.stalactite.query.model.operator.SQLFunction}).
    	 * Consumption and aggregation of query result is left to the user that must implement its {@link Accumulator}
    	 * while executing the result of this method through {@link ExecutableProjection#execute(Accumulator)}.
    	 * <strong>Note that all {@link org.codefilarete.stalactite.query.model.Selectable} added to the Select must have an alias</strong>.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param selectAdapter the {@link Select} clause modifier
    	 * @param getter1 a property accessor
    	 * @param getter2 a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O, A> ExecutableProjectionQuery<C, ?> selectProjectionWhere(Consumer<SelectAdapter<C>> selectAdapter, SerializableFunction<C, A> getter1, SerializableFunction<A, O> getter2, ConditionalOperator<O, ?> operator) {
    		return selectProjectionWhere(selectAdapter, AccessorChain.fromMethodReferences(getter1, getter2).getAccessors(), operator);
    	}

    	/**
    	 * Creates a projection query which criteria target mapped properties.
    	 * {@link Select} must be modified by given select adapter (by default all columns that would allow to load the entity are present).
    	 * User is expected to modify default {@link Select} by clearing it (optional) and add its {@link org.codefilarete.stalactite.query.model.Selectable}
    	 * ({@link org.codefilarete.stalactite.sql.ddl.structure.Column} or {@link org.codefilarete.stalactite.query.model.operator.SQLFunction}).
    	 * Consumption and aggregation of query result is left to the user that must implement its {@link Accumulator}
    	 * while executing the result of this method through {@link ExecutableProjection#execute(Accumulator)}.
    	 * <strong>Note that all {@link org.codefilarete.stalactite.query.model.Selectable} added to the Select must have an alias</strong>.
    	 * Raises an exception if targeted property is not mapped as a persisted one (transient).
    	 *
    	 * @param selectAdapter the {@link Select} clause modifier
    	 * @param accessorChain a property accessor
    	 * @param operator criteria for the property
    	 * @param <O> value type returned by property accessor
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	default <O> ExecutableProjectionQuery<C, ?> selectProjectionWhere(Consumer<SelectAdapter<C>> selectAdapter, List<? extends ValueAccessPoint<?>> accessorChain, ConditionalOperator<O, ?> operator) {
    		return selectProjectionWhere(selectAdapter).and(accessorChain, operator);
    	}

    	default <O> ExecutableProjectionQuery<C, ?> selectProjectionWhere(Consumer<SelectAdapter<C>> selectAdapter, CriteriaPath<C, ?> accessorChain, ConditionalOperator<O, ?> operator) {
    		return selectProjectionWhere(selectAdapter, accessorChain.getAccessors(), operator);
    	}

    	default <O, S extends Collection<O>, NEXT> ExecutableProjectionQuery<C, ?> selectProjectionWhere(Consumer<SelectAdapter<C>> selectAdapter, SerializableCollectionFunction<C, S, O> accessor1, SerializableFunction<O, NEXT> accessor2, ConditionalOperator<O, ?> operator) {
    		return selectProjectionWhere(selectAdapter, new CriteriaPath<>(accessor1, accessor2), operator);
    	}

    	/**
    	 * Creates a projection query which criteria target mapped properties.
    	 * {@link Select} must be modified by given select adapter (by default all columns that would allow to load the entity are present).
    	 * User is expected to modify default {@link Select} by clearing it (optional) and add its {@link org.codefilarete.stalactite.query.model.Selectable}
    	 * ({@link org.codefilarete.stalactite.sql.ddl.structure.Column} or {@link org.codefilarete.stalactite.query.model.operator.SQLFunction}).
    	 * Consumption and aggregation of query result is left to the user that must implement its {@link Accumulator}
    	 * while executing the result of this method through {@link ExecutableProjection#execute(Accumulator)}.
    	 * <strong>Note that all {@link org.codefilarete.stalactite.query.model.Selectable} added to the Select must have an alias</strong>.
    	 *
    	 * @param selectAdapter the {@link Select} clause modifier
    	 * @return a {@link EntityCriteria} enhance to be executed through {@link ExecutableQuery#execute(Accumulator)}
    	 */
    	ExecutableProjectionQuery<C, ?> selectProjectionWhere(Consumer<SelectAdapter<C>> selectAdapter);

    	Set<C> selectAll();

    	boolean isNew(C entity);

    	I getId(C entity);

    	Class<C> getClassToPersist();

    	/**
    	 * Mashup between {@link EntityCriteria} and {@link ExecutableQuery} to make an {@link EntityCriteria} executable
    	 * @param <C> type of object returned by query execution
    	 */
    	interface ExecutableEntityQuery<C, SELF extends ExecutableEntityQuery<C, SELF>> extends EntityCriteria<C, SELF>, ExecutableQuery<C>, FluentOrderByClause<C, SELF> {

    		SELF set(String paramName, Object paramValue);

    		/**
    		 * Overridden for a more accurate return type.
    		 * {@inheritDoc}
    		 */
    		ExecutableEntityQuery<C, SELF> beginNested();

    		/**
    		 * Overridden for a more accurate return type.
    		 * {@inheritDoc}
    		 */
    		ExecutableEntityQuery<C, SELF> endNested();

    	}

    	/**
    	 * Mashup between {@link EntityCriteria} and {@link ExecutableProjection} to make an {@link EntityCriteria} executable
    	 * @param <C> type of object returned by query execution
    	 */
    	interface ExecutableProjectionQuery<C, SELF extends ExecutableProjectionQuery<C, SELF>> extends EntityCriteria<C, SELF>, ExecutableProjection, FluentOrderByClause<C, SELF> {

    		SELF set(String paramName, Object paramValue);

    		/**
    		 * Overridden for a more accurate return type.
    		 * {@inheritDoc}
    		 */
    		ExecutableProjectionQuery<C, SELF> beginNested();

    		/**
    		 * Overridden for a more accurate return type.
    		 * {@inheritDoc}
    		 */
    		ExecutableProjectionQuery<C, SELF> endNested();
    	}

    	/**
    	 * Abstraction to configure the select clause of a query.
    	 *
    	 * @param <C> the type of context or entity for which the selection is configured
    	 */
    	interface SelectAdapter<C> {

    		Set<Selectable<?>> getColumns();

    		SelectAdapter<C> distinct();

    		SelectAdapter<C> setDistinct(boolean distinct);

    		SelectAdapter<C> add(Selectable<?> column);

    		SelectAdapter<C> add(Selectable<?> column, String alias);

    		default SelectAdapter<C> add(CriteriaPath<C, ?> property) {
    			return add(property.getAccessors());
    		}

    		default SelectAdapter<C> add(CriteriaPath<C, ?> property, String alias) {
    			return add(property.getAccessors(), alias);
    		}

    		default SelectAdapter<C> add(List<ValueAccessPoint<?>> property) {
    			return add(giveColumn(property));
    		}

    		default SelectAdapter<C> add(List<ValueAccessPoint<?>> property, String alias) {
    			return this.add(giveColumn(property), alias);
    		}

    		default Selectable<?> giveColumn(ValueAccessPoint<?> property) {
    			return giveColumn(Arrays.asList(property));
    		}

    		default Selectable<?> giveColumn(SerializableFunction<C, ?> property) {
    			return giveColumn(Accessors.accessorByMethodReference(property));
    		}

    		Selectable<?> giveColumn(List<ValueAccessPoint<?>> property);
    	}
    }